feat: implement service primitive by sourcehawk · Pull Request #32 · sourcehawk/operator-component-framework

sourcehawk · 2026-03-22T03:11:49Z

Implements the service Kubernetes resource primitive following the pattern established by the existing ConfigMap and Deployment primitives.

Summary

Adds service primitive package under pkg/primitives/service/
Implements required lifecycle interfaces
Includes editors, mutator, flavors, and builder

Checklist

Compiles cleanly
Tests pass
Follows naming conventions in CONTEXT.md
Does not modify shared files

Copilot

Pull request overview

Adds a new service Kubernetes primitive to the Operator Component Framework, aligning Services with the framework’s builder/mutator/flavor patterns used by existing primitives.

Changes:

Introduces pkg/primitives/service (resource, builder, mutator, flavors, handlers) plus unit tests.
Adds a new shared ServiceSpecEditor under pkg/mutation/editors (with tests) to support typed Service mutations.
Adds a runnable example (examples/service-primitive) and primitive documentation (docs/primitives/service.md).

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
pkg/primitives/service/resource.go	Service resource wrapper + default field applicator (ClusterIP preservation).
pkg/primitives/service/builder.go	Fluent builder wiring mutations, flavors, handlers, and extractors.
pkg/primitives/service/mutator.go	Plan/apply mutator with metadata + ServiceSpec edit categories.
pkg/primitives/service/handlers.go	Default operational + suspension/delete-on-suspend handlers.
pkg/primitives/service/flavors.go	Service flavors delegating to generic flavors helpers.
pkg/primitives/service/*_test.go	Unit tests for builder/mutator/handlers/flavors.
pkg/mutation/editors/servicespec.go	New typed editor API for `corev1.ServiceSpec`.
pkg/mutation/editors/servicespec_test.go	Unit tests for `ServiceSpecEditor`.
examples/service-primitive/*	End-to-end example wiring builder + feature mutations + extraction.
docs/primitives/service.md	New user-facing documentation for the service primitive.

pkg/mutation/editors/servicespec.go

pkg/primitives/service/resource.go

pkg/primitives/service/handlers.go

docs/primitives/service.md

sourcehawk · 2026-03-22T13:27:22Z

Claude Review Cycle 1 Complete

Addressed:

LoadBalancer ingress check (handlers.go:32): Fixed DefaultOperationalStatusHandler to verify that ingress entries contain a non-empty IP or Hostname before reporting Operational, rather than just checking slice length. Added test case for ingress entry with no IP/Hostname.
Missing resource_test.go (resource.go:23): Added pkg/primitives/service/resource_test.go covering Resource wrapper behaviors: Identity, Object (deep copy), Mutate (baseline + ClusterIP preservation + mutations + custom applicator), ConvergingStatus, Suspend, DeleteOnSuspend, SuspensionStatus, and ExtractData.
Doc terminology inconsistency (service.md:238): Fixed OperationPending to Pending to match the rest of the document, and updated description to reflect the new IP/hostname validation.

Intentionally ignored:

Shared editor concern (servicespec.go:15): This is a PR description/checklist accuracy issue, not a code issue. The ServiceSpecEditor is a new file added by this PR under pkg/mutation/editors — it is shared infrastructure by location but is purpose-built for the service primitive. The PR description should be updated to reflect this, but no code change is needed.

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

docs/primitives/service.md

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 7 comments.

pkg/primitives/service/resource.go

pkg/primitives/service/builder.go

pkg/mutation/editors/servicespec.go

examples/service-primitive/README.md

pkg/mutation/editors/servicespec.go

sourcehawk · 2026-03-23T02:57:35Z

Claude Review Cycle 1 Complete

Addressed:

Preserve server-populated Status (including LoadBalancer.Ingress) in DefaultFieldApplicator so ConvergingStatus correctly reports operational state for LoadBalancer Services (resource.go:20)
Fixed doc comment on WithCustomSuspendStatus: now says "leaves the Service untouched" instead of "Services are deleted on suspend" (builder.go:116)
Fixed doc comment on WithCustomSuspendMutation: now says "leaves the Service unaffected by suspension" instead of "deleted on suspend" (builder.go:132)
Fixed doc comment on WithCustomSuspendDeletionDecision: now correctly says "returns false" instead of "returns true" (builder.go:143)
Added Protocol to unnamed port matching in EnsurePort — treats empty Protocol as TCP (Kubernetes default) to avoid incorrect replacement when same port number is used with different protocols (servicespec.go:40)
Updated README suspension description to match actual default behavior (DeleteOnSuspend=false) (README.md:10)

Intentionally ignored:

Comment about PR description checklist saying "Does not modify shared files" while modifying pkg/mutation/editors/ (servicespec.go:5): This is a PR description accuracy concern, not a code issue. The servicespec.go change (adding Protocol-aware port matching) is a legitimate bug fix that belongs in this PR.

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 6 comments.

pkg/primitives/service/resource_test.go

docs/primitives/service.md

pkg/primitives/service/mutator.go

pkg/primitives/service/resource.go

sourcehawk · 2026-03-23T17:02:25Z

Claude Review Cycle 1 Complete

Addressed:

Added TestDefaultFieldApplicator_PreservesStatus to guard against regressions clearing Status.LoadBalancer.Ingress (resource_test.go:117 comment)
Added TestResource_Mutate_FeatureOrdering to verify mutation ordering across multiple features (resource_test.go:163 comment)
Updated EnsurePort docs to mention protocol matching semantics — match on Port + effective Protocol (treating empty as TCP) when Name is empty (docs/primitives/service.md:159 comment)
Fixed critical bug: exported BeginFeature() on FeatureMutator interface and all primitive mutators so cross-package mutators can satisfy the interface and receive proper feature boundary calls from ApplyMutations (mutator.go:50 comment)
Added nodePort preservation in DefaultFieldApplicator — when the desired port's NodePort is 0, the auto-allocated value from the current object is preserved, matching ports by Name or by Port+Protocol when unnamed (resource.go:26 comment)
Added TestDefaultFieldApplicator_PreservesNodePorts test for the nodePort fix

Intentionally ignored:

Markdown table || formatting (docs/primitives/service.md:14 comment): The tables already use correct single | delimiters — no || patterns exist in the file. This appears to be a false positive.

Copilot

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 4 comments.

internal/generic/mutate_helper.go

pkg/primitives/service/resource.go

internal/generic/resource_workload.go

docs/primitives/service.md

Provides typed methods for managing service ports, selectors, session affinity, traffic policies, and other ServiceSpec fields. Includes full test coverage for all editor methods. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Implements the Service primitive with: - Builder with fluent API for mutations, flavors, status handlers - Mutator with plan-and-apply pattern (metadata then spec edits) - DefaultFieldApplicator preserving immutable clusterIP/clusterIPs - DefaultOperationalStatusHandler (LoadBalancer pending until ingress assigned) - DefaultDeleteOnSuspendHandler (true - Services deleted on suspend) - PreserveCurrentLabels and PreserveCurrentAnnotations flavors - Full test coverage for builder, mutator, handlers, and flavors Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Covers building, mutations, editors, flavors, operational status, suspension behavior, data extraction, and usage guidance. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Demonstrates base construction, feature-gated mutations (version labels, metrics port), annotation preservation, operational status tracking, suspension, and data extraction with a fake client. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Use non-deprecated ServiceExternalTrafficPolicy type and rename unused test parameter. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

… fix doc terminology - Fix DefaultOperationalStatusHandler to verify ingress entries have an actual IP or Hostname before reporting Operational (not just non-empty slice) - Add resource_test.go covering Resource wrapper behaviors (Identity, Object, Mutate with ClusterIP preservation, ConvergingStatus, Suspend, ExtractData) - Fix inconsistent terminology in service.md (OperationPending -> Pending) - Add test case for ingress entries without IP/Hostname Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…comments, improve port matching - Preserve server-populated Status (including LoadBalancer.Ingress) in DefaultFieldApplicator so ConvergingStatus correctly detects assigned ingress addresses. - Fix misleading doc comments on WithCustomSuspendStatus, WithCustomSuspendMutation, and WithCustomSuspendDeletionDecision to accurately reflect that Services are left in place by default. - Include Protocol in unnamed port matching in EnsurePort to avoid incorrect replacement when same port number is used with different protocols (e.g., TCP/UDP). - Update README suspension description to match actual default behavior. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace manual status assignment with generic.PreserveStatus() to align with the deployment primitive pattern and the new shared helper. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Initialize plans slice inline and set active pointer directly, matching the fix already applied to deployment and configmap mutators. This prevents an empty feature from being created when the generic helper in mutator_helper.go calls beginFeature(). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

docs/primitives/service.md

examples/service-primitive/README.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk · 2026-03-24T18:33:30Z

Claude Review Cycle 1 Complete

Addressed:

Added service-primitive example to the run-examples Makefile target so it is included in CI and make run-examples runs.

Intentionally ignored:

Double-pipe table syntax in service.md: The tables in docs/primitives/service.md already use standard single-pipe | markdown table syntax throughout. No double pipes || exist in the file, so no changes were needed.

Copilot

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated no new comments.

…tive

…igration The framework now uses Server-Side Apply instead of ctrl.CreateOrUpdate, eliminating the need for field applicators to merge desired state onto current state. This removes DefaultFieldApplicator, WithCustomFieldApplicator, WithFieldApplicationFlavor, the flavors.go file, and updates all tests to use the Object()-then-Mutate() pattern. Documentation is updated to remove SSA and field applicator sections. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

Copilot · 2026-03-25T19:23:18Z

docs/primitives/service.md

+| Step | Category          | What it affects                          |
+| ---- | ----------------- | ---------------------------------------- |
+| 1    | Metadata edits    | Labels and annotations on the `Service`  |
+| 2    | ServiceSpec edits | Ports, selectors, type, traffic policies |
+


The "Internal Mutation Ordering" table also starts each row with ||, which adds an unintended empty column in rendered markdown. Please fix the table syntax to use | ... | consistently.

Copilot · 2026-03-25T19:23:18Z

examples/service-primitive/README.md

+- **Field Flavors**: Preserving annotations that might be managed by external tools (e.g., cloud load balancer
+  controllers).


This README claims the example demonstrates "Field Flavors" (preserving externally managed annotations), but the service primitive builder/mutator exposed in this PR doesn’t include any flavor API or implementation. Either remove this bullet or add the missing flavor support so the documentation matches the code.

Suggested change

- **Field Flavors**: Preserving annotations that might be managed by external tools (e.g., cloud load balancer

controllers).

Copilot · 2026-03-25T19:23:18Z

Makefile

 	go run ./examples/replicaset-primitive/.
 	go run ./examples/rolebinding-primitive/.
 	go run ./examples/custom-resource-implementation/.
+	go run ./examples/service-primitive/.


PR description checklist says "Does not modify shared files", but this change updates the root Makefile (and also adds shared framework code under pkg/mutation/editors and docs). Please update the PR description/checklist to reflect that shared files are modified, or move these changes to a separate PR if that’s the project expectation.

Copilot · 2026-03-25T19:23:19Z

pkg/primitives/service/resource.go

+//   - component.Resource: for basic identity and mutation behaviour.
+//   - component.Operational: for tracking whether the Service is operational.
+//   - component.Suspendable: for participating in the component suspension lifecycle.
+//   - component.DataExtractable: for exporting values after successful reconciliation.


The interface list in the Resource doc comment refers to component.Suspendable / component.DataExtractable, but the actual interfaces live under pkg/component/concepts (e.g., concepts.Suspendable). Please update the comment so it points to the correct package/interface names to avoid misleading API consumers.

Suggested change

// - component.Resource: for basic identity and mutation behaviour.

// - component.Operational: for tracking whether the Service is operational.

// - component.Suspendable: for participating in the component suspension lifecycle.

// - component.DataExtractable: for exporting values after successful reconciliation.

// - concepts.Resource: for basic identity and mutation behaviour.

// - concepts.Operational: for tracking whether the Service is operational.

// - concepts.Suspendable: for participating in the component suspension lifecycle.

// - concepts.DataExtractable: for exporting values after successful reconciliation.

sourcehawk requested a review from Copilot March 22, 2026 13:19

Copilot started reviewing on behalf of sourcehawk March 22, 2026 13:20 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

pkg/mutation/editors/servicespec.go Show resolved Hide resolved

pkg/primitives/service/resource.go Outdated Show resolved Hide resolved

pkg/primitives/service/handlers.go Outdated Show resolved Hide resolved

docs/primitives/service.md Outdated Show resolved Hide resolved

Copilot AI review requested due to automatic review settings March 22, 2026 21:54

Copilot started reviewing on behalf of sourcehawk March 22, 2026 21:54 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

docs/primitives/service.md Outdated Show resolved Hide resolved

Copilot AI review requested due to automatic review settings March 23, 2026 00:51

sourcehawk force-pushed the feature/service-primitive branch from 5094589 to 656d3c2 Compare March 23, 2026 00:51

Copilot started reviewing on behalf of sourcehawk March 23, 2026 00:51 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings March 23, 2026 16:08

Copilot started reviewing on behalf of sourcehawk March 23, 2026 16:11 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings March 23, 2026 17:02

Copilot started reviewing on behalf of sourcehawk March 23, 2026 17:02 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

internal/generic/mutate_helper.go Outdated Show resolved Hide resolved

pkg/primitives/service/resource.go Show resolved Hide resolved

internal/generic/resource_workload.go Outdated Show resolved Hide resolved

docs/primitives/service.md Outdated Show resolved Hide resolved

sourcehawk and others added 11 commits March 23, 2026 20:16

Add Service primitive documentation

363ba66

Covers building, mutations, editors, flavors, operational status, suspension behavior, data extraction, and usage guidance. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fix lint issues in ServiceSpecEditor

7d716e4

Use non-deprecated ServiceExternalTrafficPolicy type and rename unused test parameter. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

add files

ee9c24b

make service not deleted by default

80e8315

Use generic PreserveStatus in service field applicator

1954ebc

Replace manual status assignment with generic.PreserveStatus() to align with the deployment primitive pattern and the new shared helper. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk requested a review from Copilot March 24, 2026 18:26

Copilot started reviewing on behalf of sourcehawk March 24, 2026 18:26 View session

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 18:27

Copilot started reviewing on behalf of sourcehawk March 24, 2026 18:28 View session

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 18:28

Copilot started reviewing on behalf of sourcehawk March 24, 2026 18:29 View session

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 18:29

Copilot started reviewing on behalf of sourcehawk March 24, 2026 18:30 View session

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 18:31

Copilot AI reviewed Mar 24, 2026

View reviewed changes

docs/primitives/service.md Show resolved Hide resolved

examples/service-primitive/README.md Show resolved Hide resolved

Copilot started reviewing on behalf of sourcehawk March 24, 2026 18:31 View session

Add service-primitive example to run-examples Makefile target

b231013

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 18:33

Copilot started reviewing on behalf of sourcehawk March 24, 2026 18:34 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

sourcehawk and others added 3 commits March 25, 2026 14:06

Merge remote-tracking branch 'origin/main' into feature/service-primi…

b804356

…tive

Merge branch 'main' into feature/service-primitive

82714ca

Copilot AI reviewed Mar 25, 2026

View reviewed changes

		- Field Flavors: Preserving annotations that might be managed by external tools (e.g., cloud load balancer
		controllers).

Conversation

sourcehawk commented Mar 22, 2026

Summary

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 22, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 23, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 23, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 24, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!